Statement Sample Calls

1. Query statement metadata

POST {{baseURL}}/v1/statement/metadata

http headers:

x-correlation-id: {{$uuid}}
x-request-id: {{$uuid}}
x-api-key: {{$var1}}
x-jws-signature: {{$var2}}

request body

{
   "iban": "HU29120670080010034200100009",
   "dateFrom": "2024-01-01",
   "dateTo": "2024-01-31",
   "consentList": ["1111", "2222"]
}

Request parameters

• iban — the bank account number to query
• dateFrom / dateTo — the search period (YYYY-MM-DD)
• consentList — always a 2-element array: the 2 consent identifiers associated with the account. In the case of a single signature, the same identifier can be provided twice (e.g. [1, 1])

response body - successful

response body

{
"allDocRecordCount": 3,
"documents": [
    {
        "docId": 2283712,
        "genDate": "2024-01-02",
        "fileOrigName": "statement_2024_01_01.pdf",
        "iban": "HU29120670080010034200100009",
        "externalId": "2014/0000003"
    },
    {
        "docId": 2283713,
        "genDate": "2024-01-03",
        "fileOrigName": "statement_2024_01_02.pdf",
        "iban": "HU29120670080010034200100009",
        "externalId": "2014/0000004"
    },
    {
        "docId": 2283714,
        "genDate": "2024-01-16",
        "fileOrigName": "statement_2024_01_15.pdf",
        "iban": "HU29120670080010034200100009",
        "externalId": "2014/0000005"
    }
]
}

---

2. Statement download

POST {{baseURL}}/v1/statement/download

http headers:

x-correlation-id: {{$uuid}}
x-request-id: {{$uuid}}
x-api-key: {{$var1}}
x-jws-signature: {{$var2}}

request body

{
   "docId": 2283712,
   "consentList": [1, 2]
}

Request parameters

• docId — identifier of the statement to download (the documents[].docId in the step 1 response)
• consentList — always a 2-element array: the 2 consent identifiers associated with the account. In the case of a single signature, the same identifier can be provided twice (e.g. [1, 1])

response body - successful

response body

{
"docId": 2283712,
"genDate": "2024-01-02",
"fileOrigName": "statement_2024_01_01.pdf",
"iban": "HU29120670080010034200100009",
"externalId": "2014/0000003",
"metaList": [
    {
        "metaName": "CERTIFIED",
        "metaValue": "Y"
    },
    {
        "metaName": "STATEMENT_NO",
        "metaValue": "2014/0000003"
    }
],
"downloadUrl": "https://s3.eu-central-1.amazonaws.com/statements/284470/statement_2024_01_01.pdf?response-content-type=application%2Fpdf&X-Amz-Security-Token=IQoJb3JpZ2luX2Vj...",
"urlExpiresAt": "2024-01-02T08:55:40.067507520Z"
}

Download process

The downloadUrl received in the response is a time-limited link, valid for 1 minute. The statement can be downloaded in PDF format by sending a GET request to the downloadUrl or by opening it in a browser. The download must be performed immediately after receiving the response.

---

3. Start asynchronous process

Prerequisite — metadata query

Before starting the asynchronous download, step 1 — metadata query must be performed. The required docId value must be extracted from the documents[].docId field of the metadata response.

POST {{baseURL}}/v1/statement/async

http headers:

x-correlation-id: {{$uuid}}
x-request-id: {{$uuid}}
x-api-key: {{$var1}}
x-jws-signature: {{$var2}}

request body

{
   "docId": 2283712,
   "consentList": [1, 2]
}

Request parameters

• docId — identifier of the statement to download (the documents[].docId in the step 1 response)
• consentList — always a 2-element array: the 2 consent identifiers associated with the account. In the case of a single signature, the same identifier can be provided twice (e.g. [1, 1])

response body - 201 Created (new process)

response body

{
"processId": "550e8400-e29b-41d4-a716-446655440000"
}

response body - 200 OK (existing active process)

response body

{
"processId": "550e8400-e29b-41d4-a716-446655440000"
}

---

4. Query asynchronous process status

POST {{baseURL}}/v1/statement/async/status

http headers:

x-correlation-id: {{$uuid}}
x-request-id: {{$uuid}}
x-api-key: {{$var1}}
x-jws-signature: {{$var2}}

request body

{
   "processId": "550e8400-e29b-41d4-a716-446655440000",
   "consentList": [1, 2]
}

Request parameters

• processId — the process identifier received in step 3
• consentList — always a 2-element array: the 2 consent identifiers associated with the account. In the case of a single signature, the same identifier can be provided twice (e.g. [1, 1])

response body - processing in progress (IN_PROGRESS)

response body

{
"processId": "550e8400-e29b-41d4-a716-446655440000",
"status": "IN_PROGRESS"
}

response body - processing successful (DONE)

response body

{
"docId": 2283712,
"genDate": "2024-01-02",
"iban": "HU29120670080010034200100009",
"externalId": "2014/0000003",
"fileOrigName": "statement_2024_01_01.pdf",
"metaList": [
    {
        "metaName": "CERTIFIED",
        "metaValue": "Y"
    },
    {
        "metaName": "STATEMENT_NO",
        "metaValue": "2014/0000003"
    }
],
"downloadUrl": "https://s3.eu-central-1.amazonaws.com/statements/async/2283712/550e8400-e29b-41d4-a716-446655440000.pdf?X-Amz-Security-Token=...",
"urlExpiresAt": "2024-01-02T08:31:00.067507520Z",
"documentExpiresAt": "2024-01-03T23:30:00Z",
"processId": "550e8400-e29b-41d4-a716-446655440000",
"status": "DONE"
}

Download process

The downloadUrl is valid until the time indicated in the urlExpiresAt field (approximately 1 minute) — the download must be performed immediately. If the link has expired but the status is still DONE, call the status polling endpoint again: it returns a fresh downloadUrl and urlExpiresAt value — up until the documentExpiresAt time.

After the documentExpiresAt expires, the process enters EXPIRED status — a new process must be started with POST /async.

---

5. Full asynchronous flow — integration example

The asynchronous download consists of 3 steps: start the process → query status (polling) → download the PDF. The diagram below shows the full flow with all possible statuses.

Status	Meaning	Action
IN_PROGRESS	Processing in progress	Wait 2–5 sec, then query again
DONE	Ready, downloadable	GET request to downloadUrl (valid for 1 minute)
ERROR	Processing error	Decide based on errorMessage / restart
EXPIRED	Document expired	Start new process with POST

ERROR response example

response body

{
"processId": "550e8400-e29b-41d4-a716-446655440000",
"status": "ERROR",
"errorMessage": "Error description (if available)"
}

EXPIRED response example

response body

{
"processId": "550e8400-e29b-41d4-a716-446655440000",
"status": "EXPIRED"
}

Parallel requests

If multiple requests arrive for the same docId simultaneously, each client receives the same processId — the service does not start unnecessary parallel processing. It is safe to call the POST endpoint multiple times.